# 小智AI助手

```{admonition} 本文引用的文件
:class: note

- [esp32s3/docs/4_xiaozhi/1_index.rst](../../../products/mpython-s3/4_xiaozhi/1_index.rst)
- [esp32s3/docs/4_xiaozhi/1_xiaozhi.rst](../../../products/mpython-s3/4_xiaozhi/1_xiaozhi.rst)
- [esp32s3/docs/4_xiaozhi/2_xiaozhi.rst](../../../products/mpython-s3/4_xiaozhi/2_xiaozhi.rst)
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/1_index.rst](../../../products/ledong-v2/4_xiaozhi/1_index.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/1_xiaozhi.rst](../../../products/ledong-v2/4_xiaozhi/1_xiaozhi.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/2_xiaozhi.rst](../../../products/ledong-v2/4_xiaozhi/2_xiaozhi.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- `esp32s3/firmware/file_system/mpython_v3/ui/voice.py`
- `esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py`
```

## 目录
- 产品概述
- 核心业务流程
- 功能模块清单
- 数据与状态
- 关键约束与边界

## 产品概述
小智AI是基于ESP32-S3的语音对话AI助手，提供唤醒词检测、实时翻译、响应式交互等能力，并支持在管理后台切换大模型与音色。项目提供免编译固件，可直接烧录到掌控板3.0或乐动掌控2.0，快速获得智能终端体验。其开源工程基于ESP-IDF开发，便于二次开发与教育场景落地。

- 目标用户：创客、教师与学生、AI/IoT初学者与进阶开发者
- 核心价值：低门槛接入云端大模型，结合本地音频采集与播放，实现“说—听—答”的闭环体验
- 适用场景：语音助手、多语种翻译、课堂互动、智能家居控制原型、边缘AI教学演示

**章节来源**
- [esp32s3/docs/4_xiaozhi/1_xiaozhi.rst:1-31](../../../products/mpython-s3/4_xiaozhi/1_xiaozhi.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/1_xiaozhi.rst:1-31](../../../products/ledong-v2/4_xiaozhi/1_xiaozhi.rst)

## 核心业务流程
小智AI的典型使用流程如下：
- 设备准备：通过USB-C连接PC，使用mPython软件选择对应板型（掌控板3.0或乐动掌控2.0），刷入小智固件
- 上电运行：设备启动后进入小智界面，显示唤醒词提示
- 语音交互：说出唤醒词触发录音；识别结果上传至云端大模型；返回文本与语音合成结果并在设备上播放
- 角色与音色：在管理后台配置角色名称、音色与大模型；设备下次对话生效
- 扩展能力：可更换更大功率功放喇叭，或通过代码接入第三方音乐平台

```text
sequenceDiagram
participant User as "用户"
participant Device as "ESP32-S3设备"
participant Cloud as "云端大模型/TTS服务"
participant UI as "LVGL界面"
participant Audio as "音频子系统"
User->>Device : 说出唤醒词
Device->>Audio : 采集麦克风音频
Device->>Cloud : 发送语音识别请求
Cloud-->>Device : 返回识别文本
Device->>Cloud : 发送对话上下文与问题
Cloud-->>Device : 返回回答文本
Device->>Audio : 调用TTS生成语音
Audio-->>Device : 播放回复语音
Device->>UI : 更新界面状态与提示
User-->>Device : 继续对话或结束
```

**图表来源**
- [esp32s3/docs/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/mpython-s3/4_xiaozhi/2_xiaozhi.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/ledong-v2/4_xiaozhi/2_xiaozhi.rst)
- `esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`
- `esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`

**章节来源**
- [esp32s3/docs/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/mpython-s3/4_xiaozhi/2_xiaozhi.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/ledong-v2/4_xiaozhi/2_xiaozhi.rst)

## 功能模块清单
- 设备与固件
  - 支持板型：掌控板3.0、乐动掌控2.0
  - 烧录方式：mPython软件选择板型后一键刷入小智固件
  - 参考路径：[esp32s3/docs/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/mpython-s3/4_xiaozhi/2_xiaozhi.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/ledong-v2/4_xiaozhi/2_xiaozhi.rst)

- 语音交互与界面
  - 唤醒词检测与命令词识别：通过语音识别接口初始化与添加命令，定时轮询最新识别结果
  - LVGL界面：显示唤醒词提示、动画与返回操作
  - 参考路径：`esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`、`esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`

- 云端大模型与音色管理
  - 支持模型：Qwen 2.5（实时）、DeepSeek V3、DouBao 1.5 Pro、Qwen Max 2.5
  - 管理后台：在控制台/设备管理/配置角色页面切换模型与音色
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:7-15](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:7-15](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

- 音频硬件与扩展
  - 默认数字功放MAX98357，支持约3W喇叭；如需更大功率需I2S功放模块与独立供电
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

- 声纹识别
  - 可在后台为说话人添加语音记录，实现“听声辨人”
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

**章节来源**
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:7-15](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:7-15](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- `esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`
- `esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`

## 数据与状态
- 语音识别状态
  - 初始化：设置唤醒词与命令词集合，更新识别器
  - 轮询：定时器回调中读取最新识别ID，执行相应动作（如RGB灯控制）
  - 参考路径：`esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`、`esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`

- 界面状态
  - 容器与画布：创建LVGL容器与背景色
  - 标签与布局：显示“唤醒词”“命令词”提示与返回按钮
  - 动画：循环绘制动画图片以提示设备处于监听状态
  - 参考路径：`esp32s3/firmware/file_system/mpython_v3/ui/voice.py:61-112`、`esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:61-112`

- 角色与音色配置
  - 角色名称：在管理后台修改，保存后生效
  - 音色切换：在后台试听并提交，下次对话使用新音色
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:22-28](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:22-28](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

```text
flowchart TD
Start(["开始"]) --> Init["初始化语音识别<br/>设置唤醒词与命令词"]
Init --> Loop{"定时器回调"}
Loop --> Read["读取最新识别ID"]
Read --> HasResult{"是否有效？"}
HasResult -- 否 --> Loop
HasResult -- 是 --> Action{"执行对应动作"}
Action --> RGB["控制RGB灯/其他外设"]
Action --> Play["播放提示音或音乐"]
RGB --> Loop
Play --> Loop
```

**图表来源**
- `esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`
- `esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`

**章节来源**
- `esp32s3/firmware/file_system/mpython_v3/ui/voice.py:20-26`
- `esp32s3/firmware/file_system/labplus_Ledong_v2/ui/voice.py:20-26`
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:22-28](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:22-28](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

## 关键约束与边界
- 网络与服务依赖
  - 语音识别与TTS需要联网访问云端服务；请确保设备已连接WiFi
  - 大模型与音色配置通过管理后台完成，设备侧无需手动配置API密钥
  - 参考路径：[esp32s3/docs/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/mpython-s3/4_xiaozhi/2_xiaozhi.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/2_xiaozhi.rst:19-38](../../../products/ledong-v2/4_xiaozhi/2_xiaozhi.rst)

- 硬件与功耗
  - 默认功放支持约3W喇叭；更高功率需I2S功放与独立供电
  - USB供电一般不超过5W，注意整体功耗与散热
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

- 版权与内容限制
  - 内置测试音乐受版权限制，仅可使用测试曲目与网友提交歌曲
  - 如需更多音乐资源，可通过扩展IO或代码接入第三方平台
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:4-5](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:4-5](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

- 识别准确率与个性化
  - 声纹识别准确率受环境、录音质量与说话人数影响
  - 建议录制较长且清晰的语音以提升识别效果
  - 参考路径：[esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)、[esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)

**章节来源**
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:4-5](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:4-5](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:18-19](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/mpython-s3/4_xiaozhi/3_xiaozhi-faq.rst)
- [esp32s3/docs/boards/ledong_v2/4_xiaozhi/3_xiaozhi-faq.rst:30-38](../../../products/ledong-v2/4_xiaozhi/3_xiaozhi-faq.rst)